{/* Copyright 2020 Adobe. All rights reserved.
This file is licensed to you under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License. You may obtain a copy
of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under
the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
OF ANY KIND, either express or implied. See the License for the specific language
governing permissions and limitations under the License. */}

import {Layout} from '@react-spectrum/docs';
export default Layout;

import docs from 'docs:@react-spectrum/color';
import {HeaderInfo, PropTable, TypeLink, PageDescription} from '@react-spectrum/docs';
import packageData from '@react-spectrum/color/package.json';
import statelyDocs from 'docs:@react-stately/color';
import colorTypes from 'docs:@react-types/color/src/index.d.ts';

```jsx import
import {ColorField} from '@react-spectrum/color';
import {Flex} from '@react-spectrum/layout';
```

---
category: Color
keywords: [color field, input]
---

# ColorField

<PageDescription>{docs.exports.ColorField.description}</PageDescription>

<HeaderInfo
  packageData={packageData}
  componentNames={['ColorField']}
  sourceData={[]}
  since="3.35.0" />

## Example

```tsx example
<ColorField label="Primary Color" />
```

## Value

A ColorField's `value` is empty by default, but an initial, uncontrolled, value can be provided using the `defaultValue` prop.
Alternatively, a controlled value can be provided using the `value` prop.  The value provided to either of these props should be a color string or <TypeLink links={colorTypes.links} type={colorTypes.exports.Color} /> object.

In the example below, the <TypeLink links={statelyDocs.links} type={statelyDocs.exports.parseColor} /> function is used to parse the initial color
from a hex value, stored in state.

```tsx example
import {parseColor} from '@react-stately/color';

function Example() {
  let [value, setValue] = React.useState(parseColor('#e73623'));

  return (
    <Flex gap="size-150" wrap>
      <ColorField
        label="Primary Color (Uncontrolled)"
        defaultValue="#e21" />

      <ColorField
        label="Primary Color (Controlled)"
        value={value}
        onChange={setValue} />
    </Flex>
  );
}
```

### HTML forms

ColorField supports the `name` prop for integration with HTML forms. The value will be submitted to the server as a hex color string. When a `channel` prop is provided, the value will be submitted as a number instead.

```tsx example
<ColorField label="Color" name="color" />
```

## Color channel

By default, ColorField allows the user to edit the color as a hex value. When the `colorSpace` and `channel` props are provided, ColorField displays the value for that channel formatted as a number instead. Rendering multiple ColorFields together can allow a user to edit a color.

```tsx example
function Example() {
  let [color, setColor] = React.useState(parseColor('#7f007f'));
  return (
    <>
      <div style={{display: 'flex', gap: 8}}>
        <ColorField label="Hue" value={color} onChange={setColor} colorSpace="hsl" channel="hue" />
        <ColorField label="Saturation" value={color} onChange={setColor} colorSpace="hsl" channel="saturation" />
        <ColorField label="Lightness" value={color} onChange={setColor} colorSpace="hsl" channel="lightness" />
      </div>
      <p>Current color value: {color?.toString('hex')}</p>
    </>
  );
}
```

## Labeling

A visual label should be provided for the ColorField using the `label` prop. If the ColorField is required, the `isRequired` and
`necessityIndicator` props can be used to show a required state.

```tsx example
<Flex gap="size-150" wrap>
  <ColorField label="Primary Color" />
  <ColorField label="Primary Color" isRequired />
  <ColorField label="Primary Color" isRequired necessityIndicator="label" />
  <ColorField label="Primary Color" necessityIndicator="label" />
</Flex>
```

### Accessibility

If a visible label isn't specified, an `aria-label` must be provided to the ColorField for
accessibility. If the field is labeled by a separate element, an `aria-labelledby` prop must be provided using
the `id` of the labeling element instead.

### Internationalization

In order to internationalize a ColorField, a localized string should be passed to the `label` or `aria-label` prop.
When the `necessityIndicator` prop is set to `"label"`, a localized string will be provided for `"(required)"` or `"(optional)"` automatically.

## Validation

ColorField supports the `isRequired` prop to ensure the user enters a value, as well as custom validation functions, realtime validation, and server-side validation. It can also be integrated with other form libraries. See the [Forms](forms.html) guide to learn more.

When the [Form](Form.html) component has the `validationBehavior="native"` prop, validation errors block form submission and are displayed as help text automatically. Errors are displayed when the user blurs the color field or submits the form.

```tsx example
import {Form, ButtonGroup, Button} from '@adobe/react-spectrum';

<Form validationBehavior="native" maxWidth="size-3000">
  {/*- begin highlight -*/}
  <ColorField label="Color" name="color" isRequired />
  {/*- end highlight -*/}
  <ButtonGroup>
    <Button type="submit" variant="primary">Submit</Button>
    <Button type="reset" variant="secondary">Reset</Button>
  </ButtonGroup>
</Form>
```

By default, `ColorField` displays default validation messages provided by the browser. See [Customizing error messages](forms.html#customizing-error-messages) in the Forms guide to learn how to provide your own custom errors.

## Props

<PropTable component={docs.exports.ColorField} links={docs.links} />

## Visual options

### Quiet

```tsx example
<ColorField label="Primary Color" isQuiet />
```

### Disabled

```tsx example
<ColorField label="Primary Color" isDisabled defaultValue="#e73623" />
```

### Read only

The `isReadOnly` boolean prop makes the ColorField's text content immutable. Unlike `isDisabled`, the ColorField remains focusable
and the contents can still be copied. See [the MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/readonly) for more information.

```tsx example
<ColorField label="Primary Color" isReadOnly defaultValue="#e73623" />
```

### Label alignment and position
[View guidelines](https://spectrum.adobe.com/page/text-field/#Label-position)

By default, the label is positioned above the ColorField. The `labelPosition` prop can be used to position the label to the side.
The `labelAlign` prop can be used to align the label as "start" or "end". For left-to-right (LTR) languages, "start" refers to the
left most edge of the ColorField and "end" refers to the right most edge. For right-to-left (RTL) languages, this is flipped.

```tsx example
<ColorField label="Primary Color" labelPosition="side" labelAlign="end" />
```

### Help text
[View guidelines](https://spectrum.adobe.com/page/help-text/)

Both a description and an error message can be supplied to a ColorField. The description is always visible unless the `validationState` is “invalid” and an error message is provided. The error message can be used to help the user fix their input quickly and should be specific to the detected error. All strings should be localized.

```tsx example
<Flex gap="size-100" wrap>
  <ColorField label="Color" defaultValue="#abc" validationState="valid" description="Enter your favorite color." />
  <ColorField label="Color" validationState="invalid" errorMessage="Empty input is not allowed." />
</Flex>
```

### Contextual help

A [ContextualHelp](ContextualHelp.html) element may be placed next to the label to provide additional information or help about a ColorField.

```tsx example
import {Content, ContextualHelp, Heading} from '@adobe/react-spectrum';

<ColorField
  label="Accent Color"
  defaultValue="#e73623"
  contextualHelp={
    <ContextualHelp>
      <Heading>What is an accent color?</Heading>
      <Content>An accent color is the primary foreground color for your theme, used across all components.</Content>
    </ContextualHelp>
  } />
```

### Custom width

[View guidelines](https://spectrum.adobe.com/page/text-field/#Width)

```tsx example
<ColorField label="Primary Color" width="size-3600" maxWidth="100%" />
```
